\section{Drag and Drop}
Naturally, draging and droping of \src{Dockable}s is a key feature of the framework. Funny enough, the code actually involved in DnD is rather small compared to other modules of the framework.

\subsection{Relocator}
The sourcecode that detects drag gestures, searches for the target station and makes sure that the user has some visual feedback is located in the \linebreak \src{DefaultDockRelocator}. \src{DefaultDockRelocator} itself extends from \linebreak \src{DockRelocator} which just allows to register some listeners and set some useful properties.

\classbox{Clients seldomly need to implement their own \src{DockRelocator}. If they do, they have to implement a new \src{DockControllerFactory} in order to install their customized class. The method \src{createRelocator} is responsible for creating the new object.

This factory has then to be given to the constructor of a \src{DockController}.}

The \src{DockRelocator} that is in use can be accessed through the method \src{getRelocator} of \src{DockController}.

\subsection{Deciding what element to drag}
The \src{Relocator} needs to know where and when the user presses and moves the mouse. There are two solutions to this problem: either let the \src{Relocator} know what \src{Component}s are shown, or remotely control the \src{Relocator}. The first solution is achieved with \src{DockElementRepresentative}s, the second solution is achieved with the \src{RemoteRelocator}.

\subsubsection{DockElementRepresentative}
A \src{DockElementRepresentative} is a \src{Component} which represents a \src{Dockable}. Anyone can add \src{MouseInputListener}s to a representative and hence be informed about anything the mouse does on top of such a \src{Component}.

While the internal implementations of \src{DockElementRepresentative} are handled automatically by the framework, clients introducing new representatives will have to call the methods \src{addRepresentative} and \src{remoteRepresentative} of \src{DockController} to install or uninstall the item.

\infobox{\src{DockElementRepresentative} was added late to the framework. It carries some legacy code: the method \src{isUsedAsTitle}. This method introduces a distinction between those representations for which all features are activated (e.g. popup menus) and those for which only a selected subset is available. Normally clients implement representatives that are used as title and can return \src{true} here.}

\warningbox{The behavior for representations of \src{Dockable}s that are not registered is unspecified. Clients should not add a \src{DockElementRepresentative} if its \src{Dockable} is unknown to the \src{DockController}.}

\subsubsection{Remote control}
Sometimes it is not possible to implement a \src{DockElementRepresentative}. Remote control of a relocator is an alternative for these cases. Remote control is realized by the \src{RemoteRelocator}.

A \src{RemoteRelocator} can be obtained by calling \src{createRemote} of \linebreak \src{DockRelocator}. \src{RemoteRelocator} should be used in combination with a \linebreak \src{MouseListener} and a \src{MouseMotionListener}:
\begin{itemize}
 \item \src{MouseListener.mousePressed} \textrightarrow \src{RemoteRelocator.init}
 \item \src{MouseMotionListener.mouseDragged} \textrightarrow \src{RemoteRelocator.drag}
 \item \src{MouseListener.mouseReleased} \textrightarrow \src{RemoteRelocator.drop}
\end{itemize}
The methods \src{init}, \src{drag} and \src{drop} return a \src{Reaction}. The reaction tells the caller what to do next:
\begin{itemize}
 \item \src{CONTINUE}: the operation continues, the event was ignored.
 \item \src{CONTINUE\_CONSUMED}: the operation continues, the event was consumed. The caller should invoke \src{MouseEvent.consume}.
 \item \src{BREAK}: the operation was canceled, the event was ignored.
 \item \src{BREAK\_CONSUMED}: the operation was canceled, the event was consumed. The caller should invoke \src{MouseEvent.consume}.
\end{itemize}

\classbox{There is a second interface called \src{DirectRemoteRelocator}. Instances can be obtained by calling \src{createDirectRemote} of \src{DockRelocator}. A \src{DirectRemoteRelocator} is basically the same as a \src{RemoteRelocator} but always assumes that the user pressed the correct button on the mouse. Its methods do not return a \src{Reaction} because the event would always be consumed anyway.}

\infobox{Clients can use several remote controls at the same time, they will cancel out each other if necessary. A \src{RemoteRelocator} can be used several times.}

\subsection{Deciding where to drop an element}
A relocator needs to find the one \src{DockStation} on which the \src{Dockable} should be dropped. There is a default search algorithm which just orders all \src{DockStation}s by importance and visits them, and there are some interfaces which can influence the search.

\subsubsection{Search}
The \src{DefaultDockRelocator} searches the destination anew whenever the mouse is moved. A search consists of these steps::
\begin{enumerate}
 \item An ordered list of all potential destinations is built. A \src{DockStation} is a potential destination if it is visible (\src{isStationShowing} of \src{DockStation}), not the dragged \src{Dockable} nor one of its children. Each station offers a set of \src{DockStationDropLayer}s (\src{getLayers}), the layers decide whether the mouse is over a station or not. The order of the destinations depends on the priority of the layers, the parent-child relations between the stations and between the \src{Window}s on which the stations are.
 \item Then the method \src{prepareDrop} of \src{DockStation} is called. This method checks whether the station really is a good destination, if so it returns a \src{StationDropOperation}. The first station returning an operation is the destination.
 \item The method \src{draw} of the new operation is called, the method \src{destroy} on the old operation. The new operation will paint some markings to give a visual feedback to the user.
\end{enumerate}

\infobox{There is more information about the exact semantics in the API-documentation for \src{DockStation}.}

\classbox{Most of the work for drag and drop is done by the \src{DockStation}s themselfs, the \src{DockRelocator} just connects them. In order to complete the task the following methods and interfaces should be used:

\begin{itemize}
 \item \src{DockStation.accept} and \src{Dockable.accept} tells the station whether a child-parent relation is possible.
 \item \src{DockController.getAcceptance} allows access to the global \src{DockAcceptance}, an additional restriction that should be checked before allowing a drag and drop operation.
 \item To paint on the station, a \src{StationPaint} should be used. A \src{StationPaint} can be accessed through the \src{ThemeManager}.
\end{itemize}
}

\subsubsection{Drop}
Once the user releases the mouse, \src{Dockable} is dropped. The framework will call the method \src{execute} of \src{StationDropOperation}.

\begin{itemize}
 \item The \src{Dockable} may just be dropped aside of all the other children of the station. All that happens is that the \src{DockStation} gets a new child.
 \item The \src{Dockable} may be dropped over another child of the station. In this case the station may decide to combine the two children. The future parent \src{DockStation} will access a \src{Combiner} which defines how exactly two \src{Dockable}s can be merged into one, usually the answer is by creating a new \src{StackDockStation}. Clients can replace the current \src{Combiner} through the \src{ThemeManager}.
 \item If the dragged \src{Dockable} is a \src{DockStation} itself, it may be feasible to merge the parent and the new child \src{DockStation} into one station. The interface \src{Merger} is responsible for that. Clients can replace the default \src{Merger} by calling \src{DockRelocator.setMerger}.
\end{itemize}

\warningbox{Exchanging a \src{Combiner} or the \src{Merger} does not affect any existing \src{Dockable} or \src{DockStation}, it will only affect the creation of new elements.}

\subsection{Restrictions}
Not every possible \src{DockStation} is a good or valid target for a dragged \src{Dockable}. The framework applies a set of restrictions to drag and drop operations, these restrictions are implemented by ``acceptance tests''. Each acceptance test can veto against some child parent relations. The usual reasons why clients would want to implement their own tests consist of:
\begin{itemize}
 \item Some \src{Dockable} must always be visible.
 \item Some \src{DockStation}s represent a special area that can only be used by a subset of \src{Dockable}s.
 \item Some \src{Dockable}s can only be presented on a certain kind of \src{DockStation}.
\end{itemize}

Acceptance tests are performed during the drag and drop operation, but also if one of \src{DockStation.drop} methods is called. The acceptance tests are implemented by these methods:
\begin{itemize}
 \item Every \src{Dockable} has two methods called \src{accept}. One method checks whether the \src{Dockable} can be put directly onto some new parent, the other method checks whether the \src{Dockable} can be combined with an already existing child.
 \item Each \src{DockStation} has a method \src{accept}. This method tells whether some \src{Dockable} can become a child of the \src{DockStation}.
 \item And then there are \src{DockAcceptance}s. A \src{DockAcceptance} has \src{accept}-methods too. These methods get a \src{DockStation} and some \src{Dockable}s, and then have to decide whether the elements can be put together. Each \src{DockAcceptance} works on a global scale, and thus they are registered at the \src{DockController} through \src{addAcceptance}.
\end{itemize}

\warningbox{Acceptance tests are very powerful. They have to be implemented carefully or the drag and drop mechanism might become crippled.}

\designbox{Acceptance tests are performed by the potential destination \src{DockStation}. The \src{DockStation} is the first module that knows where a \src{Dockable} will land. Handling acceptance tests allows the station to cut down the amount of work it does, and to try alternative actions (e.g. a ``put'' instead of a ``merge'' action) if some future configuration does not pass the tests.

The drawback is, that a \src{DockStation} can break the mechanism by just not performing the tests.}

\subsection{Modes}
A \src{DockRelocator} can have "modes". A mode is some kind of behavior that is activated when the user presses a certain combination of keys. Modes are modeled by the class \src{DockRelocatorMode}. It is not specified what effect a mode really has, but normally a mode would add some restrictions where to put a \src{Dockable} during drag and drop. \src{DockRelocatorMode}s can be added or removed to a \src{DockRelocator} by the methods \src{addMode} and \src{removeMode}.

Currently two modes are installed:
\begin{description}
\item[DockRelocatorMode.SCREEN\_ONLY] (press key \textit{shift}) ensures that a \linebreak \src{Dockable} can only be put on a \src{ScreenDockStation}. That means that a \src{Dockable} can be directly above a \src{DockStation} like a \src{SplitDockStation}, but can't be dropped there.
\item[DockRelocatorMode.NO\_COMBINATION] (press key \textit{alt}) ensures that a \src{Dockable} can't be put over another \src{Dockable}. That means, every operation that would result in a merge is forbidden. Also dropping a \src{Dockable} on already merged \src{Dockable}s will not be allowed.
\end{description}

\classbox{The keys that have to be pressed to activate \src{SCREEN\_ONLY} or \src{NO\_COMBINATION} are the properties \src{SCREEN\_MASK} and \src{NO\_COMBINATION\_MASK}. The can be changed by accessing the \src{DockProperties}.}

\subsection{Animations}
During drag and drop, the framework may show some animations to help the user understand what effects dropping the \src{Dockable} would have. The animations usually involve moving or resizing the \src{Dockable}s that are not dragged. These animations are implemented with help of the \src{Span} interface. Each \src{Span} object represents some gap in the layout, a \src{Span} basically is a self mutating integer, to be understood as the size of a gap in pixels. Each \src{DockStation} may use several \src{Span}s at the same time, and an animation may involve multiple \src{Span}s changing their value simultaneously.

\infobox{ There are two sides involved in the animations:
\begin{itemize}
 \item The \src{DockStation}s define \emph{where} and \emph{when} the animations appear. For example a \src{FlapDockStation} can trigger an animation to insert empty space between each of its buttons.
 \item The \src{Span}s define \emph{how} an animation looks like. For example a \src{Span} could be implemented such that an animation starts slowly and increases its speed over time.
\end{itemize}}
Clients cannot tell a \src{DockStation} where the animations take place, but they can influence how the animations look like. To do that, clients need to implement both the \src{Span} and the \src{SpanFactory} interface. The \src{DockStation} will configure the \src{Span}, by associating different sizes (number of pixels) to different \src{SpanMode}s, and later by telling the \src{Span} which \src{SpanMode} currently is required. In return the \src{Span} will call the \src{resized} method of the \src{SpanCallback} whenever the size of the gap changes.

\classbox{To install a new \src{SpanFactory} clients can:
\begin{itemize}
 \item Use the property key \src{DockTheme.SPAN\_FACTORY} to globally change the factory.
 \item Use \src{ThemeManager.setSpanFactory} to change the factory only for one class of \src{DockStation}s.
 \item Calling \src{setSpanFactory} of \src{BasicTheme} \emph{before} the theme is installed.
\end{itemize}}
\warningbox{Some themes, like the \src{EclipseTheme}, deliberately disable the animations by installing the \src{NoSpanFactory}. }

